<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>The Apache Tomcat 5.5 Servlet/JSP Container - Load Balancer HOW-TO</title><meta content="Yoav Shapira" name="author"><meta content="Remy Maucherat" name="author"><meta content="Andy Oliver" name="author"><style media="print" type="text/css">
			.noPrint {display: none;}
			td#mainBody {width: 100%;}
		</style></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
      The Apache Tomcat Servlet/JSP Container
    " align="right" src="./../images/tomcat.gif"></a></td><td><h1><font face="arial,helvetica,sanserif">The Apache Tomcat 5.5 Servlet/JSP Container</font></h1></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./../images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><tr><!--RIGHT SIDE MAIN BODY--><td id="mainBody" align="left" valign="top" width="80%"><h1>The Apache Tomcat 5.5 Servlet/JSP Container</h1><h2>Load Balancer HOW-TO</h2><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Table of Contents"><!--()--></a><a name="Table_of_Contents"><strong>Table of Contents</strong></a></font></td></tr><tr><td><blockquote>
<ul><li><a href="#Using_the_JK_1.2.x_native_connector">Using the JK 1.2.x native connector</a></li><li><a href="#Using_Apache_HTTP_Server_2.x_with_mod_proxy">Using Apache HTTP Server 2.x with mod_proxy</a></li><li><a href="#Using_the_balancer_webapp">Using the balancer webapp</a><ol><li><a href="#Overview">Overview</a></li><li><a href="#Sample_Configuration">Sample Configuration</a></li><li><a href="#Balancer_Rules">Balancer Rules</a></li><li><a href="#How_it_Works">How it Works</a></li><li><a href="#Comments">Comments</a></li></ol></li></ul>
</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Using the JK 1.2.x native connector"><!--()--></a><a name="Using_the_JK_1.2.x_native_connector"><strong>Using the JK 1.2.x native connector</strong></a></font></td></tr><tr><td><blockquote>

Please refer to the JK 1.2.x documentation.

</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Using Apache HTTP Server 2.x with mod_proxy"><!--()--></a><a name="Using_Apache_HTTP_Server_2.x_with_mod_proxy"><strong>Using Apache HTTP Server 2.x with mod_proxy</strong></a></font></td></tr><tr><td><blockquote>

Please refer to the mod_proxy documentation for Apache HTTP Server 2.2. This supports either
HTTP or AJP load balancing. This new version of mod_proxy is also usable with
Apache HTTP Server 2.0, but mod_proxy will have to be compiled separately using the code
from Apache HTTP Server 2.2.

</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Using the balancer webapp"><!--()--></a><a name="Using_the_balancer_webapp"><strong>Using the balancer webapp</strong></a></font></td></tr><tr><td><blockquote>

<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Overview"><strong>Overview</strong></a></font></td></tr><tr><td><blockquote>

<p>
Tomcat 5.0.15 and later ships with a webapp named balancer.  This is
a simple implementation of a rules-based load balancer.  It was not designed
as a replacement for other load-balancing mechanisms used for high traffic
environments.  Rather, it is a simple, pure Java, easily extensible, and fast
way to direct traffic among multiple servers.
</p>
<p>
Although balancer ships with Tomcat, it is not Tomcat-specific and runs
on other containers without any modification.  The balancer webapp 
requires a Servlet Specification 2.3 or later container if you wish 
to use a filter to redirect traffic.  If you wish to redirect traffic
using a servlet, you may use any servlet container.
</p>
</blockquote></td></tr></table>

<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Sample Configuration"><!--()--></a><a name="Sample_Configuration"><strong>Sample Configuration</strong></a></font></td></tr><tr><td><blockquote>
<p>
The default balancer installation uses a single filter, BalancerFilter,
mapped to all requests (url-pattern /*).  The filter reads its rules
from the location specified in the balancer deployment descriptor
(web.xml file).  The default rules are:
<ul>
  <li>Redirect requests with News in the URL to www.cnn.com</li>
  <li>Redirect requests with a parameter named paramName whose
value is paramValue to www.yahoo.com.</li>
  <li>Redirect all other requests to jakarta.apache.org.</li>
</ul>

Therefore, when you install tomcat, start it, and point your
browser to http://localhost:8080/balancer, you will be redirected
to http://jakarta.apache.org.  If you point your browser to
http://localhost:8080/balancer/News you will be redirected to
http://www.cnn.com.  The request for 
http://localhost:8080/balancer/BlahBlah?paramName=paramValue will
be redirected to http://www.yahoo.com.
</p>
</blockquote></td></tr></table>

<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Balancer Rules"><!--()--></a><a name="Balancer_Rules"><strong>Balancer Rules</strong></a></font></td></tr><tr><td><blockquote>
<p>
A <i>Rule</i> in the balancer system is a combination of
a request matching criterion and a redirection URL for
matching requests.  Rules implement the
org.apache.webapp.balancer.Rule interface.
</p>

<p>
The balancer distribution contains a number of useful
rules.  The framework is also designed for easy extensibility
so that you can write your own rules quickly.  Rules
should be JavaBeans (public no-args constructor, public
setter method setXXX for property xxx), as they are
instantiated by Jakarta Commons Digester.  Feel free
to inquire on the tomcat-user mailing list regarding
the availability of rules or the inclusion of your rules
in the distribution.
</p>

<p>
Rules are assembled into RuleChains.  Each BalancerFilter
(or Servlet/JSP) refers to one RuleChain when making its
redirection decisions.  Note that you are not restricted
to having one filter mapped to /* as done in the sample
configuration.  You can configure as many filters as
desired, using the full filter mapping possibilities defined
in the Servlet Specification.  Each filter will have
its own RuleChain.
</p>
</blockquote></td></tr></table>

<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="How it Works"><!--()--></a><a name="How_it_Works"><strong>How it Works</strong></a></font></td></tr><tr><td><blockquote>
<p>
<ol>
  <li>You write a rules configuration file containing various
rules and redirection locations.</li>
  <li>You define the balancer filter in your web.xml, mapping
it as desired (/* is a common use-case) and configuring it
with your rules configuration file.</li>
  <li>The server is started, initializing the filter.</li>
  <li>A request comes into the server.  The filter consults
its rule chain to determine where to redirect the request.  Rules
are consulted in the order in which they are defined in the rules
configuration file.  The first matching rule will stop the
evaluation and cause the request to be redirected.</li>
</ol>
</p>

</blockquote></td></tr></table>

<table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#828DA6"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Comments"><strong>Comments</strong></a></font></td></tr><tr><td><blockquote>
<p>
Please direct questions, comments, suggestions, etc. to the
tomcat-user mailing list.  Thank you.
</p>
</blockquote></td></tr></table>

</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade="noshade"></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
        Copyright &copy; 1999-2011, Apache Software Foundation
        </em></font></div></td></tr></table></body></html>